AutoIt

v3.2.0.1

©1999-2006 Jonathan Bennett & AutoIt Team

AutoIt v3 Homepage

Introduction

AutoIt v3 is a freeware BASIC-like scripting language designed for automating the Windows GUI. It uses a combination of simulated keystrokes, mouse movement and window/control manipulation in order to automate tasks in a way not possible or reliable with other languages (e.g. VBScript and SendKeys).

AutoIt was initially designed for PC "roll out" situations to configure thousands of PCs, but with the arrival of v3 it is also well suited to performing home automation and the scripting of repetitive tasks.

AutoIt can:

  • Execute Windows and DOS executables
  • Simulate key strokes (supports most keyboards layouts)
  • Simulate mouse movements and clicks
  • Move, resize and manipulate windows
  • Interact directly with "controls" on a window (set/get text, move, disable, etc.)
  • Work with the clipboard to cut/paste text items
  • Work with the registry

Unlike AutoIt v2, the new v3 language has a much more standard syntax -similar to VBScript and BASIC - and now supports complex expressions, user functions, looping and everything else that veteran scripters would expect.

As with previous versions, AutoIt has been designed to be as small as possible and stand-alone with no external .dll files or registry entries required. Scripts can also be compiled into stand-alone executables with Aut2Exe.

There have also been updates to the ActiveX and DLL versions of AutoIt called AutoItX - unlike v2 this will be a combined control (COM and standard DLL functions in the same DLL). AutoItX will allow you to add the unique features of AutoIt to your own favourite scripting or programming languages! See the AutoItX Help file (Start \ AutoIt v3 \ Extras \ AutoItX \ AutoItX Help File) for more information and examples.

Best of all, AutoIt continues to be FREE - but if you want to support the time, money and effort spent on the project and web hosting then you may donate at the AutoIt homepage.

What's New?

v3 has a completely different syntax to v2.64 so old scripts are not compatible. However, v2.64 will continue to be supported and downloadable. Both AutoIt v3 and v2.64 can be installed on the same machine together without any problems and you can keep your old scripts intact. v2 uses the .aut extension and v3 uses .au3. There is rarely a need to rewrite a working v2.64 script for v3.

v3 has the same concepts as previous versions with windows titles and text and keyboard and mouse simulation but has many new features:

Controls

Directly get information on and interact with edit boxes, check boxes, list boxes, combos, buttons, status bars without the risk of keystrokes getting lost. Even work with controls in windows that aren't active!

Language Upgrades

"Proper" numbers, unlimited-length strings, complex expressions, if statements, select, while loops, for loops, do loops, functions, arrays, excellent string handling (over 25 functions!) - the list goes on. Everything you need to make your automation routines as painless as possible. Yes, this is a GUI automation language but the syntax in v3 is powerful enough for general purpose scripting. Old versions of AutoIt were often referred to as "not a proper language". Not any more.

Key and Mouse Simulation

Much time has been spent optimizing the keystroke and mouse simulation functions to be as accurate as possible on all current operating systems. The mouse functions also look more "human" in this version and can even be used to create slick demo scripts. All the mouse and keyboard routines are highly configurable both in terms of simulation "speed" and functionality.

Window Management

In addition to the "title/text" v2 way of accessing windows you can also access windows by their class names and handles. As usual you can expect to move, hide, show, resize, activate, close and pretty much do what you want with windows.

And much, much more.


CREDITS
=======

AutoIt v3 is based on the original AutoIt program by Jonathan Bennett.

Programming
===========

Core Programming and framework (and style police)
-------------------------------------------------
- Jonathan Bennett <jon at autoitscript com>

Contributions
-------------
Names are listed in NO PARTICULAR ORDER.  The script commands that were influenced/created by the contributors
are also given where possible - if you are not mentioned and think you should be then drop me a mail.

- Larry Keys <larrydalooza at yahoo com>

    AutoIt Window Spy, AU3GUI and

    ControlFocus, ControlLeftClick, @IPAddressNN, FileGetSize, FileGetTime, FileOpenDialog,
    FileSaveDialog, FileSelectFolder, DiskSpaceTotal, DiskSpaceFree, PixelSearch, PixelGetColor,
    FileCreateShortcut, WinSetOnTop, FileExists, DriveGetDrive, CDTray, ControlSetText,
    ControlGetText, ControlCommand, ControlMove, ControlEnable, ControlDisable, ControlShow,
    ControlHide, WinGetClassList, IsAdmin, SplashImageOn, SplashTestOn, SplashOff
    ProgressOn, ProgressOff, ProgressSet, DriveGetLabel, DriveGetSerial, DriveGetFileSystem,
    DriveSetLabel, DriveGetType, MouseGetCursor, FileFindFirstFile, FileFindNextFile,
    ControlGetFocus

- David Nuttall <danuttall at rocketmail com>

    General C++ advice,
    StringIsAlpha, StringIsLower, StringIsUpper, StringIsDigit, StringIsAlNum, StringIsXDigit, StringIsSpace,
    StringIsASCII, RegDelete, Asc, DirRemove, DirCreate, Random, UBound, FileRecycle, IsArray, IsInt, IsFloat,
    IsString, StringStripWS, Mod, InputBox, variabletable.cpp rewrite and binary tree prototypes, new function
    lookup design/ideas, Redim, unified Structure stack, ContinueLoop, Util_MouseDown, Util_MouseUp (primary/secondary),
    Binary Search code for function lookup, StringRegExp... functions, initialize arrays, Floor, Ceiling,
    Const keyword to UDF parameters, AutoItSetOption rewrite, IsBool, variable assignment, Switch, ContinueCase, BitRotate

- J-Paul Mesnage <jpm at autoitscript com>

    v2 to v3 Converter, AU3GUI and

    Lots of bug reports, regression testing and ideas/prototypes,
    @OSServicePack, @OSBuild, @AutoItVersion, AutoItWinShow, AutoItWinWrite, SoundPlay, StringFormat
    @OSLang, Hex, AutoItWinGetText, _ Continuation, Single-line IFs, Dim/Global/Local same line initialisation,
    TrayTipDebug, better non-English keyboard support for Send functions, optional UDF parameters, GUI graphics,
    TCP functions, GUICtrlCreateMonthCal, Execute("expression"), Default keyword, isKeyword,
    OnAutoItExit extension, AutoIt Info Style and exStyle

    Prototypes for: Error/include tracking code, Local/Global

- Jason Boggs <vampire dot valik at gmail com>

    #include <> multiple directories, TrayTip, ToolTip, MemGetStats, new function lookup design/ideas,
    PID support in process functions and Run(), ProcessSetPriority, Assign, ConsoleWrite, ProcessList,
    WinSetTrans, IniReadSectionNames, IniReadSection, IniRenameSection, Enum, DllCall extensions,
    explicit Return @error/@extended, @AutoItPID, ConsoleWriteError, SetError extension, HWnd, IsHWnd

- Tylo <tylo at start.no>

    Float lexing and double to string conversions.  Some math functions (tan, atan, etc.)
    vector_datatype.h, stack_datatype.h, variable_table.cpp rewrite (discontinued), new function lookup
    design/ideas, +=, -=, *=, /= operators

- Jeremy Landes <jlandes at landeserve com>

    Standard include files compilation and

    XP Visual Styles manifest files.  Some math functions (Abs, Pow, Sqrt, etc.)
    @UserName, @TempDir, @UserProfileDir, @HomeDrive, @HomePath, @HomeShare, @LogonServer,
    @LogonDomain, @LogonDNSDomain

- Philip "CyberSlug" Gump <cyberslug at autoitscript com>

    ControlCommand(GetCurrentCol)

- Jos van der Zande <jvdzande at yahoo com>

    Misc bug fixes, Scite lexer, Standard include files.

- Holger <Holger.Kotsch at GMX de>

    AU3GUI (especially Menus, Treeviews and ContextMenus) and

    FileGetShortcut, FileCreateShortcut, FileSelectFolder, @DesktopRefresh, Ping, Tray functions
    @HotKeyPressed, GuiCtrlSetImage extension, GuiCtrlListView iconview

- Garrett "The HardlyDeservesCreditFor20LinesOfCode" R. Mueller ;) <garrett at mailsnare.net>

    TimerInit, TimerDiff

- Dave Fulgham <DaveF@ditch.org>

    StdoutRead, StderrRead, StdinWrite, ConsoleRead

- SvenP
    Obj/COM functions, Boolean support, GUICtrlCreateObj

- Ejoc
    DLLStruct... functions

- layer <... at ... ...>
    Beep, WinFlash

- /dev/null <... at ... ...>
    UDPStartup, UDPShutdown, UDPSend, UDPRecv, UDPOpen, UDPBind

- gafrost <... at ... ...>
    GUI include files

External contributions and other sources used
---------------------------------------------

- Amir Szekely <kichik at netvision net il>

    ResourceEditor.cpp - Resource editing functions (works on 9x too)
    Thanks to Amir who coded the resource functions for the NSIS Installer and helped me
    get the code working with AutoIt.  Check out the NSIS installer at:
    http://nsis.sourceforge.net/site/index.php

- Gabriele Scibilia <http://www.geocities.com/gabriele_scibilia/>

    qmath.h - used with permission.


AutoIt

Credits

In no particular order, but thank you all! (-Jon)

Please see here for details of the coding contributions. (Email me if you have been left out).

AutoIt v3 Coding

- Jonathan Bennett <jon at autoitscript com>

- Larry Keys <larrydalooza at yahoo com>

- David Nuttall <nutster at autoit3 com>

- J-Paul Mesnage <jpm at autoitscript com>

- Jason Boggs <vampire dot valik at gmail com>

- Tylo <tylo at start no>

- Jeremy Landes <jlandes at landeserve com>

- Philip "CyberSlug" Gump <cyberslug at autoitscript com>

- Jos van der Zande <jdeb at autoitscript com >

- Holger <Holger.Kotsch at GMX de>

- SvenP < ... at ... nl>

- Dave Fulgham <DaveF at ditch org>

- Ejoc < ... at ... ...>

-/dev/null <... at ... ...>

- Garrett "The HardlyDeservesCreditFor20LinesOfCode" R. Mueller ;) <garrett at mailsnare net>

AutoIt v3 Help Files

- Most of the above ;p

- Philip "CyberSlug" Gump <cyberslug at autoitscript com> (and helper scripts)

- Jos van der Zande <jdeb at autoitscript com> (and helper scripts)

- ScriptKitty <scriptkitty at autoitscript com>

AutoIt v3 Standard Includes

- The authors as documented in the include files themselves.

- Jos van der Zande <jdeb at autoitscript com>

- Jeremy Landes <jlandes at landeserve com>

- Brian Keene <brian_keene at juno com>

- gafrost <... at ... ...>

Many thanks to the above for compiling/modifying them all.

AutoIt v3 Extras and Third Party Tools

- JdeB <jdeb at autoitscript com> (AutoIt version of the Scite editor)

Special Thanks

- Everyone who continues to use and support AutoIt

- Jeremy Landes for providing extra download capacity at http://www.landeserve.com

- The authors of UPX which is used for creating compressed executables produced by AutoIt.


Function FileInstall

Function Reference

FileInstall

Include and install a file with the compiled script.

FileInstall ( "source", "dest" [, flag] )

Parameters

source | The source path of the file to compile. This must be a literal string; it cannot be a variable.
dest | The destination path with trailing backslash. This can be a variable.
flag | [optional] this flag determines whether to overwrite files if they already exist: 0 = (default) do not overwrite existing files 1 = overwrite existing files

Return Value

Success: | Returns 1.
Failure: | Returns 0.

Remarks

The FileInstall function is designed to include files into a compiled AutoIt script. These included files can then be "extracted" during execution of the compiled script if the statement is executed. Keep in mind that files such as images can greatly increase the size of a compiled script.
The source file must be a string and not a variable so that the compiler can extract the filename to include. The source cannot contain wildcards.

When this function is used from a non-compiled script, a copy operation is performed instead (to allow for easy testing pre-compilation).
Files maintain their original creation/modification timestamps when installed.

Related

#Include

Example

; Include a bitmap found in "C:\test.bmp" with the compiled program and put it in "D:\mydir\test.bmp" when it is run
$b = True
If $b = True Then FileInstall("C:\test.bmp", "D:\mydir\test.bmp")


Compiling Scripts with Aut2Exe

It is possible to take your .au3 script and compile it into a standalone executable; this executable can be used without the need for AutoIt to be installed and without the need to have AutoIt3.exe on the machine. In addition, the compiled script is compressed and encrypted and there is the option to bind additional files (also compressed/encrypted) to the exe using the FileInstall function. Also, any #include files will also be compiled into the script so they are not required at run-time.

Aut2Exe can be used in three ways:

Method 1 - Start Menu

Only available if full install performed.

1. Open the Start Menu and browse to the AutoIt v3 group.

2. Click Script Compiler \ Convert .au3 to .exe

3. The main Aut2Exe interface should appear.

4. Use the Browse buttons to select your input (.au3) and output (.exe) files.

5. If you like you can change the icon of the resulting .exe - just browse to the icon you want (some example icons are supplied in Program Files\AutoIt3\Aut2Exe\Icons).

6. If you don't want anyone to be able to decompile your script (when a decompiler is made available) then you should enter a passphrase.

7. The only other option you might wish to change is the compression level (especially if using FileInstall to add extra files). Use the Compression menu to set this. As with all compression routines the better the compression you select the slower it will be. However, no matter what compression level you select the decompression speed (when the .exe is run) is the same.

8. Click on Convert to compile the script.

Note: scripts can be compile with .a3x extension. They should be run with AutoIt.exe filename.a3x. The .a3x contains the script itself plus the FileInstall files. This format allow to distribute smaller files as they don't include the AutoIt3.exe in each compile script. You still need to have it accessible on the target machine but just AutoIt3.exe.

Method 2 - Right Click

Only available if full install performed.

1. In Explorer browse to the .au3 file that you wish to compile.

2. Right-click the file to access the pop-up menu.

3. The file will be silently compiled with the same filename - just with a .exe extension.

When compiling in this way, Aut2Exe uses current icon/compression settings (from the last time Aut2Exe was run manually as in method 1).

Method 3 - The Command Line

The Aut2Exe.exe program can be run from the command line as follows:

Aut2exe.exe /in <infile.au3> [/out <outfile.exe>] [/icon <iconfile.ico>] [/nodecompile] [/comp 0-4] [/pass <passphrase>]

Long filenames should be enclosed in double-quotes like "C:\Program Files\Test\test.au3". If no "out" file is given the input filename is used with a .exe extension.

Technical Details

The compiled script and additional files added with FileInstall are compressed with my own (Jon) compression scheme.

Because a compiled script must "run" itself without a password it needs to be able to decrypt itself - i.e., the encryption is two-way. For this reason you should regard the compiled exe as being encoded rather than completely safe. For example, if I wrote a script that contained a username and password (say, for a desktop rollout) then I would be happy using something like a workstation-level user/password but I would not consider it safe for a domain/entire network password unless I was sure that the end-user would not have easy access to the .exe file.


Keyword #include

Keyword Reference

#include

Includes a file in the current script.

#include "[path\]filename"
#include <filename>

Parameters

filename The filename of the current script to include. Path is optional. This must be a string--it cannot be a variable.
If "..." is used, the filename is taken to be relative to the current script.
If <...> is used the filename is taken to be relative to include library directory (usually C:\Program Files\AutoIt3\Include). The include library contains many pre-written user-functions for you to use!

Remarks

In an AutoIt script, other scripts can be included using the #include" command.

For the include library syntax (#include <file>) to work AutoIt must have been installed using the supplied installer otherwise the installation directory will not be known and the current script directory (@ScriptDir\Include) will be used instead.

If you include the same file containing a user-function more than once you will get a "Duplicate function" error. When writing an include file that may be used in this way, make sure that the top line contains #include-once to prevent that file from being included more than once.

There is a special registry value that can be created at "HKEY_CURRENT_USER\Software\AutoIt v3\AutoIt" called "Include". It should be a REG_SZ (string) value. The contents of this value are a semi-colon delimited list of directories that should be searched for files when resolving #include's in addition to the standard locations.

The search order used by AutoIt depends on which form of #include you use. The tables below show the order directories are searched using both forms.

Using #include <>
Standard library | The path of the currently running interpreter with "\Include" appended is searched.
User-defined libraries | The registry value mentioned above is read and each directory is searched in the order they appear in.
Script directory | The directory of the currently executing script.

Using #include "" (This is the reverse of #include <>).
Script directory | The directory of the currently executing script.
User-defined libraries | The registry value mentioned above is read and each directory is searched in the reverse order they appear in.
Standard library | The path of the currently running interpreter with "\Include" appended is searched.

A note about using the /AutoIt3ExecuteScript option. Since the standard library is searched for in the current interpreter's directory, the standard library functions will not be found; that library will only be found when run through AutoIt3.exe. It's recommended that you compile a script to the .a3x format before attempting to run it with /AutoIt3ExecuteScript.

Aut2Exe uses the same algorithm as AutoIt3.exe with the only difference being it looks for the Include sub-directory as being in a sibling directory to itself (..\Include).

If Opt("TrayIconDebug",1) only 64 include files name can be displayed in the traytooltip. for the other no filename will be displayed.

Related

#include-once, FileInstall

Example

;;; TIME.AU3 ;;;
MsgBox(0,"", "The time is " & @HOUR & ":" & @MIN & ":" & @SEC)

;;; SCRIPT.AU3 ;;;
#include "TIME.AU3"
MsgBox(0,"", "Example")
#include "TIME.AU3"
Exit

; Running script.au3 will output three message boxes:
; one with the time, one with 'Example', and another with the time.


Keyword #include-once

Keyword Reference

#include-once

Specifies that the current file may only be included once.

#include-once

Parameters

None.

Remarks

If you include the same file containing a user-function more than once, you will get a "Duplicate function" error. When writing an include file that may be used in this way, make sure that the top line contains #include-once to prevent that file from being included more than once.

Related

#include, FileInstall

Example

;;; LIBRARY.AU3 ;;;
#include-once

Func myFunc()
MsgBox(0,"", "Hello from library.au3")
EndFunc

;;; SCRIPT.AU3 ;;;
#include "Library.au3"
#include "Library.au3" ;throws an error if #include-once was not used

MsgBox(0, "Example", "This is from 'script.au3' file")
myFunc()
Exit

; Running script.au3 will output the two message boxes:
; one saying "This is from 'script.au3' file"
; and another saying "Hello from library.au3"